Recurring Payments | Vodacom Payment Services

Tokenise - Phase 1 - Flow diagram

Request

Production Url

UAT Url

QA Url

https://psp.vodacompaymentgateway.co.za/recurringPayment/tokenize

https://uat.vodacompaymentgateway.co.za/recurringPayment/tokenize

https://qa.vodacompaymentgateway.co.za/recurringPayment/tokenize

Encryption Xml

Encryption Xml Xsd

Encryption Xml Description


<transaction>
    <amount></amount>
    <currency></currency>
    <password></password>
    <username></username>
    <identifier></identifier>
    <transactiontype></transactiontype>
    <payserveralias></payserveralias>
    <product>
        <type></type>
        <salestype></salestype>
        <reference></reference>
        <productcode></productcode>
        <productamount></productamount>
        <productdescription></productdescription>
    </product>
    <merchantreference></merchantreference>
    <requestidentifier></requestidentifier>
    <customeridentifier></customeridentifier>
    <merchantidentifier></merchantidentifier>
    <recurringaction></recurringaction>
    <notifyurl></notifyurl>
    <failureurl></failureurl>
    <returnurl></returnurl>
    <webhookurl></webhookurl>
    <webhookpayload></webhookpayload>
    <webhookverb></webhookverb>
</transaction>


<Transaction>
    <Amount></Amount>
    <Currency></Currency>
    <Password></Password>
    <Username></Username>
    <Identifier></Identifier>
    <TransactionType></TransactionType>
    <PayserverAlias></PayserverAlias>
    <Product>
        <Type></Type>
        <SalesType></SalesType>
        <Reference></Reference>
        <ProductCode></ProductCode>
        <ProductAmount></ProductAmount>
        <ProductDescription></ProductDescription>
    </Product>
    <MerchantReference></MerchantReference>
    <RequestIdentifier></RequestIdentifier>
    <CustomerIdentifier></CustomerIdentifier>
    <MerchantTokenReference></MerchantTokenReference>	
    <MerchantIdentifier></MerchantIdentifier>
    <RecurringAction></RecurringAction>
    <NotifyUrl></NotifyUrl>
    <FailureUrl></FailureUrl>
    <ReturnUrl></ReturnUrl>
    <WebHooks>
        <WebHook>
	    <Template></Template>
	    <Type></Type>
	    <Url></Url>
        </WebHook>
    </WebHooks>
</Transaction>


<xs:schema attributeformdefault="unqualified" elementformdefault="qualified" xmlns:xs="http://www.w3.org/2001/XMLSchema">
    <xs:element name="Transaction">
        <xs:complextype>
            <xs:sequence>
                <xs:element type="xs:decimal" name="Amount" minoccurs="1" maxoccurs="1"></xs:element>
                <xs:element name="Currency" minoccurs="1" maxoccurs="1">
                    <xs:simpletype>
                        <xs:restriction base="xs:string">
                            <xs:pattern value="[A-Z]{3}"></xs:pattern>
                        </xs:restriction>
                    </xs:simpletype>
                </xs:element>
                <xs:element name="Password" minoccurs="1" maxoccurs="1">
                    <xs:simpletype name="LimitedString">
                        <xs:restriction base="xs:string">
                            <xs:maxlength value="350"></xs:maxlength>
                        </xs:restriction>
                    </xs:simpletype>
                </xs:element>
                <xs:element name="Username" minoccurs="1" maxoccurs="1">
                    <xs:simpletype name="LimitedString">
                        <xs:restriction base="xs:string">
                            <xs:maxlength value="50"></xs:maxlength>
                        </xs:restriction>
                    </xs:simpletype>
                </xs:element>
                <xs:element name="Identifier" minoccurs="1" maxoccurs="1">
                    <xs:simpletype name="LimitedString">
                        <xs:restriction base="xs:string">
                            <xs:maxlength value="250"></xs:maxlength>
                        </xs:restriction>
                    </xs:simpletype>
                </xs:element>
                <xs:element name="TransactionType" minoccurs="1" maxoccurs="1">
                    <xs:simpletype>
                        <xs:restriction base="xs:string">
                            <xs:pattern value="01|02"></xs:pattern>
                        </xs:restriction>
                    </xs:simpletype>
                </xs:element>
                <xs:element type="xs:string" name="PayserverAlias" minoccurs="1" maxoccurs="1"></xs:element>
                <xs:element name="Product" minoccurs="0" maxoccurs="unbounded">
                    <xs:complextype>
                        <xs:sequence>
                            <xs:element name="Type" type="xs:string" minoccurs="0" maxoccurs="1">
                                <xs:simpletype name="Reference" minoccurs="0" maxoccurs="1">
                                    <xs:restriction base="xs:string">
                                        <xs:maxlength value="50"></xs:maxlength>
                                    </xs:restriction>
                                    <xs:documentation>Recharge Type | Airtime|PPD</xs:documentation>
                                </xs:simpletype>
                            </xs:element>
                            <xs:element name="SalesType" minoccurs="0" maxoccurs="1">
                                <xs:simpletype>
                                    <xs:restriction base="xs:string">
                                        <xs:pattern value="01|03"></xs:pattern>
                                    </xs:restriction>
                                </xs:simpletype>
                            </xs:element>
                            <xs:element name="Reference" minoccurs="0" maxoccurs="1">
                                <xs:simpletype name="LimitedString">
                                    <xs:restriction base="xs:string">
                                        <xs:maxlength value="50"></xs:maxlength>
                                    </xs:restriction>
                                    <xs:documentation>MSISDN for Recharge</xs:documentation>
                                </xs:simpletype>
                            </xs:element>
                            <xs:element name="ProductCode" minoccurs="0" maxoccurs="1">
                                <xs:simpletype name="LimitedString">
                                    <xs:restriction base="xs:string">
                                        <xs:maxlength value="50"></xs:maxlength>
                                    </xs:restriction>
                                    <xs:documentation>Recharge Code</xs:documentation>
                                </xs:simpletype>
                            </xs:element>
                            <xs:element type="xs:decimal" name="ProductAmount" minoccurs="0" maxoccurs="1"></xs:element>
                            <xs:element name="ProductDescription" minoccurs="0" maxoccurs="1">
                                <xs:simpletype name="LimitedString">
                                    <xs:restriction base="xs:string">
                                        <xs:maxlength value="500"></xs:maxlength>
                                    </xs:restriction>
                                </xs:simpletype>
                            </xs:element>
                        </xs:sequence>
                    </xs:complextype>
                </xs:element>
                <xs:element name="MerchantReference" minoccurs="1" maxoccurs="1">
                    <xs:simpletype name="LimitedString">
                        <xs:restriction base="xs:string">
                            <xs:maxlength value="50"></xs:maxlength>
                        </xs:restriction>
                    </xs:simpletype>
                </xs:element>
                <xs:element name="RequestIdentifier" minoccurs="1" maxoccurs="1">
                    <xs:simpletype name="LimitedString">
                        <xs:restriction base="xs:string">
                            <xs:maxlength value="50"></xs:maxlength>
                        </xs:restriction>
                    </xs:simpletype>
                </xs:element>
                <xs:element name="CustomerIdentifier" minoccurs="1" maxoccurs="1">
                    <xs:simpletype name="LimitedString">
                        <xs:restriction base="xs:string">
                            <xs:maxlength value="250"></xs:maxlength>
                        </xs:restriction>
                    </xs:simpletype>
                </xs:element>
                <xs:element name="MerchantTokenReference" minoccurs="0" maxoccurs="1">
                    <xs:simpletype name="LimitedString">
                        <xs:restriction base="string">
                            <xs:maxlength value="250"></xs:maxlength>
                        </xs:restriction>
                    </xs:simpletype>
                </xs:element>
                <xs:element name="MerchantIdentifier" minoccurs="1" maxoccurs="1">
                    <xs:simpletype name="GUIDType">
                        <xs:restriction base="string">
                            <xs:pattern value="\{[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}\}"></xs:pattern>
                        </xs:restriction>
                    </xs:simpletype>
                </xs:element>
                <xs:element name="RecurringAction" minoccurs="1" maxoccurs="1">
                    <xs:simpletype>
                        <xs:restriction base="xs:string">
                            <xs:pattern value="1|2"></xs:pattern>
                        </xs:restriction>
                    </xs:simpletype>
                </xs:element>
                <xs:element name="NotifyUrl" minoccurs="1" maxoccurs="1">
                    <xs:simpletype name="LimitedString">
                        <xs:restriction base="xs:string">
                            <xs:maxlength value="500"></xs:maxlength>
                        </xs:restriction>
                    </xs:simpletype>
                </xs:element>
                <xs:element name="FailureUrl" minoccurs="1" maxoccurs="1">
                    <xs:simpletype name="LimitedString">
                        <xs:restriction base="xs:string">
                            <xs:maxlength value="500"></xs:maxlength>
                        </xs:restriction>
                    </xs:simpletype>
                </xs:element>
                <xs:element name="ReturnUrl" minoccurs="1" maxoccurs="1">
                    <xs:simpletype name="LimitedString">
                        <xs:restriction base="xs:string">
                            <xs:maxlength value="500"></xs:maxlength>
                        </xs:restriction>
                    </xs:simpletype>
                </xs:element>
		<xs:element name="Webhooks" minoccurs="1" maxoccurs="unbounded">
		    <xs:complextype>
		        <xs:sequence>
		            <xs:element name="Webhook" minoccurs="1" maxoccurs="unbounded">
			        <xs:complextype>
				    <xs:sequence>
                                        <xs:element name="Template" minoccurs="1" maxoccurs="1">
	                                    <xs:simpletype name="LimitedString">
					        <xs:restriction base="xs:string">
					            <xs:maxlength value="500"></xs:maxlength>
					        </xs:restriction>
					     </xs:simpletype>
					</xs:element>
                                        <xs:element name="Type" minoccurs="1" maxoccurs="1">
	                                    <xs:simpletype name="LimitedString">
					        <xs:restriction base="xs:string">
					            <xs:pattern value="GET|POST"></xs:pattern>
					        </xs:restriction>
					     </xs:simpletype>
					</xs:element>
                                        <xs:element name="Url" minoccurs="1" maxoccurs="1">
	                                    <xs:simpletype name="LimitedString">
					        <xs:restriction base="xs:string">
					            <xs:maxlength value="500"></xs:maxlength>
					        </xs:restriction>
					    </xs:simpletype>
					</xs:element>
				    </xs:sequence>
	                        </xs:complextype>
			    </xs:element>
		        </xs:sequence>
		    </xs:complextype>
		</xs:element>
            </xs:sequence>
        </xs:complextype>
    </xs:element>
</xs:schema>

TransactionType : This determines whether the payment must be an Auth (02) or an Auth and Settle (01)

CustomerIdentifier : A unique value that will be used to uniquely identify the customeridentifier

RecurringAction : This determines whether the tokenisation is a subscribe () or and update (). An update will overide the current token or add a new one, while the subscribe wil only add a new profile and fail if one already exists

ReturnUrl / FailureUrl : This is the redirect urls after the initial payment has either been authed or authed and settled.

NotifyUrl : This is the url that the async token response will be posted to once ABSA has responsed with the successful token created

Url : This is the url that the async transaction result will be posted to

Template : Base64 encoded string used for the aync transaction result post

Form Post


<input type="hidden" name="PayserverUser" id="PayserverUser" value="">
<input type="hidden" name="EncType" id="EncType" value="">
<input type="hidden" name="EncSalt" id="EncSalt" value="">
<input type="hidden" name="EncIterations" id="EncIterations" value="">
<input type="hidden" name="EncIv" id="EncIv" value="">
<input type="hidden" name="EncXml" id="EncXml" value="">
<input type="hidden" name="ReturnUrl" id="ReturnUrl" value="">
<input type="hidden" name="NotifyUrl" id="NotifyUrl" value="">
<input type="hidden" name="FailureUrl" id="FailureUrl" value="">

Immediate Response

Transaction Response


<input name="MerchantIdentifier" type="hidden" value="">
<input name="MerchantReference" type="hidden" value="">
<input name="CorrelationIdentifier" type="hidden" value="" data-example="requestIdentifier">
<input name="CustomerIdentifier" type="hidden" value="">
<input name="CardNumber" type="hidden" value="">
<input name="Amount" type="hidden" value="">
<input name="TransactionReference" type="hidden" value="" data-example="TransactionID">
<input name="ErrorCode" type="hidden" value="">
<input name="ErrorDescription" type="hidden" value="">
<input name="BankReference" type="hidden" value="" data-example="RRN">
<input name="BankResponseCode" type="hidden" value="" data-example="isoCode">
<input name="BankResponseDescription" type="hidden" value="" data-example="isoMessage">
<input name="ControlKey" type="hidden" value="">

Async Response

Transaction Response

Base64 decoded from the webhookpayload received from the initial payload. Below are the fields that can be sent back to the merchant.


{
  "Type":"RecurringPaymentCallBack",
  "ControlKey":"#ControlKey#",
  "Identifier": "#Identifier#",
  "MerchantReference": "#MerchantReference#",
  "Amount": "#Amount#",
  "RequestIdentifier": "#RequestIdentifier#",
  "TransactionReference": "#TransactionReference#",
  "TransactionId": "#TransactionId#",
  "ErrorDescription": "#ErrorDescription#",
  "ErrorCode": "#ErrorCode#",
  "BankResponseDescription": "#BankResponseDescription#",
  "BankResponseCode": "#BankResponseCode#",
  "TransactionStatus": "#TransactionStatus#",
  "Currency": "#Currency#",
  "SupplierID": "#SupplierID#",
  "Stamp": "#Stamp#",
  "CustomerIdentifier": "#CustomerIdentifier#",
  "MerchantIdentifier": "#MerchantIdentifier#",
  "MaskedCardNumber": "#MaskedCardNumber#",
  "RetrievalReferenceNumber": "#RetrievalReferenceNumber#"
}

Post Back

Tokenise Response

This response is async and relys on the bank for a response.


{
  "merchantid": "",
  "tokenstatusid": "",
  "merchanttokenid": "",
  "bankresponsemessage": "",
  "merchanttokenreference": "",
  "merchantcustomerreference": "",
  "tokenstatus": ""
}

Payment - Phase 2 - Flow diagram

Request

Production Url

UAT Url

QA Url

https://psp.vodacompaymentgateway.co.za/api/recurring/pay

https://uat.vodacompaymentgateway.co.za/api/recurring/pay

https://qa.vodacompaymentgateway.co.za/api/recurring/pay

Encryption Xml

Encryption Xml Xsd


<recurringpayment>
    <merchantid></merchantid>
    <password></password>
    <payserveralias></payserveralias>
    <url></url>
    <payment>
        <amount></amount>
        <currency></currency>
        <ordernumber></ordernumber>
        <merchanttokenid></merchanttokenid>
        <merchantcustomerreference></merchantcustomerreference>
        <product>
            <type></type>
            <code></code>
            <salestype></salestype>
            <reference></reference>
            <description></description>
        </product>
    </payment>
        <payment>
        <amount></amount>
        <currency></currency>
        <ordernumber></ordernumber>
        <merchanttokenid></merchanttokenid>
        <merchantcustomerreference></merchantcustomerreference>
        <merchanttokenreference></merchanttokenreference>
        <product>
            <type></type>
            <code></code>
            <salestype></salestype>
            <reference></reference>
            <description></description>
        </product>
    </payment>
</recurringpayment>


<xs:schema attributeformdefault="unqualified" elementformdefault="qualified" xmlns:xs="http://www.w3.org/2001/XMLSchema">
  <xs:element name="recurringpayment">
    <xs:complextype>
      <xs:sequence>
        <xs:element name="merchantid" minoccurs="1" maxoccurs="1">
          <xs:simpletype name="GUIDType">
            <xs:restriction base="string">
              <xs:pattern value="\{[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}\}"></xs:pattern>
            </xs:restriction>
          </xs:simpletype>
        </xs:element>
        <xs:element name="password" minoccurs="1" maxoccurs="1">
          <xs:simpletype name="LimitedString">
            <xs:restriction base="xs:string">
              <xs:maxlength value="350"></xs:maxlength>
            </xs:restriction>
          </xs:simpletype>
        </xs:element>
        <xs:element name="payserveralias" minoccurs="1" maxoccurs="1">
          <xs:simpletype name="LimitedString">
            <xs:restriction base="xs:string">
              <xs:maxlength value="255"></xs:maxlength>
            </xs:restriction>
          </xs:simpletype>
        </xs:element>
        <xs:element name="url" minoccurs="1" maxoccurs="1">
          <xs:simpletype name="URL">
            <xs:restriction base="xs:anyURI">
              <xs:pattern value="http://.+"></xs:pattern>
            </xs:restriction>
          </xs:simpletype>
        </xs:element>
        <xs:element name="payment" minoccurs="1" maxoccurs="1">
          <xs:complextype>
            <xs:sequence>
              <xs:element type="xs:decimal" name="amount" minoccurs="1" maxoccurs="1"></xs:element>
              <xs:element name="currency" minoccurs="1" maxoccurs="1">
                <xs:simpletype>
                  <xs:restriction base="xs:string">
                    <xs:pattern value="[A-Z]{3}"></xs:pattern>
                  </xs:restriction>
                </xs:simpletype>
              </xs:element>
              <xs:element type="xs:string" name="ordernumber" minoccurs="0" maxoccurs="1">
                <xs:simpletype name="LimitedString">
                  <xs:restriction base="xs:string">
                    <xs:maxlength value="32"></xs:maxlength>
                  </xs:restriction>
                </xs:simpletype>
              </xs:element>
              <xs:element name="merchanttokenid">
                <xs:simpletype name="GUIDType">
                  <xs:restriction base="string">
                    <xs:pattern value="\{[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}\}"></xs:pattern>
                  </xs:restriction>
                </xs:simpletype>
              </xs:element>
              <xs:element name="merchantcustomerreference" minoccurs="1" maxoccurs="1">
                <xs:simpletype name="LimitedString">
                  <xs:restriction base="xs:string">
                    <xs:maxlength value="250"></xs:maxlength>
                  </xs:restriction>
                </xs:simpletype>
              </xs:element>
              <xs:element name="merchanttokenreference" minoccurs="0" maxoccurs="1">
                <xs:simpletype name="LimitedString">
                  <xs:restriction base="xs:string">
                    <xs:maxlength value="250"></xs:maxlength>
                  </xs:restriction>
                </xs:simpletype>
              </xs:element>
              <xs:element name="product" minoccurs="0" maxoccurs="unbounded">
                <xs:complextype mixed="true">
                  <xs:sequence>
                    <xs:element name="type" minoccurs="0" maxoccurs="1">
                      <xs:simpletype name="LimitedString">
                        <xs:restriction base="xs:string">
                          <xs:maxlength value="50"></xs:maxlength>
                        </xs:restriction>
                        <xs:documentation>recharge type | airtime|ppd</xs:documentation>
                      </xs:simpletype>
                    </xs:element>
                    <xs:element name="code" minoccurs="0" maxoccurs="1">
                      <xs:simpletype name="LimitedString">
                        <xs:restriction base="xs:string">
                          <xs:maxlength value="50"></xs:maxlength>
                        </xs:restriction>
                      </xs:simpletype>
                    </xs:element>
                    <xs:element name="salestype" minoccurs="0" maxoccurs="1">
                      <xs:simpletype>
                        <xs:restriction base="xs:string">
                          <xs:pattern value="01|03"></xs:pattern>
                        </xs:restriction>
                        <xs:documentation>recharge type</xs:documentation>
                      </xs:simpletype>
                    </xs:element>
                    <xs:element name="reference" minoccurs="0" maxoccurs="1">
                      <xs:simpletype name="LimitedString">
                        <xs:restriction base="xs:string">
                          <xs:maxlength value="50"></xs:maxlength>
                        </xs:restriction>
                        <xs:documentation>msisdn for recharge</xs:documentation>
                      </xs:simpletype>
                    </xs:element>
                    <xs:element name="description" minoccurs="0" maxoccurs="1">
                      <xs:simpletype name="LimitedString">
                        <xs:restriction base="xs:string">
                          <xs:maxlength value="500"></xs:maxlength>
                        </xs:restriction>
                      </xs:simpletype>
                    </xs:element>
                  </xs:sequence>
                </xs:complextype>
              </xs:element>
            </xs:sequence>
          </xs:complextype>
        </xs:element>
      </xs:sequence>
    </xs:complextype>
  </xs:element>
</xs:schema>

API Post


{
  "PayserverUsername": "",
  "EncryptionType": "",
  "EncryptionSalt": "",
  "EncryptionIterations": 0,
  "EncryptionIv": "",
  "EncryptionXml": ""
}

Response

Payment Response


{
  "WasSuccessful": true,
  "Message": "",
  "Error": {
    "ErrorCode": "",
    "ErrorDescription": ""
  },
  "Exception": {
    "Message": "",
    "Source": "",
    "StackTrace": "",
    "InnerException": {},
  }
}

Post Back

payment Response


{
  "id": "",
  "statusid": "",
  "authcode": "",
  "ordernumber": "",
  "bankresponsemessage": "",
  "retrievalreferencenumber": "",
  "status": ""
}